It wasn't a hacker that took down our payment gateway last year. It wasn't a DDoS attack or a memory leak. זה היה דייב. ובכן, באופן ספציפי, זה היה העובדה שדייב החליט לעבור לחווה כבשים בוורמונט, השאיר מאחוריו 15,000 שורות של קוד ספגטי שעבד את כל ההיגיון החיוב חוזר שלנו. מצאתי את ההערה הזו מועילה: BillingService.js // TODO: Fix this hack later. It's ugly but it works. - Dave, 2019 אין הגדרות פרמטרים, אין סוגים של חזרה, אין הסבר מדוע קו 405 היה מחולק על ידי משתנה שנקרא . We spent three days reverse-engineering our own product while customers churned. magicNumber אנו מתייחסים לתיעוד הקוד כמו לפלוס: אנחנו יודעים שאנחנו do it, we lie to our dentists (managers) about doing it, but we only actually do it when things start to rot. צריך But what if you didn't have to write it? What if you could have a Technical Writer with 10 years of experience sitting next to you, turning your cryptic Python scripts into pristine, Sphinx-ready documentation in seconds? הפסקתי לצפות שהמפתחים יהיו משוררים. . Agentic Documentation Strategy אפידמיה של "כתוב רק" בסיס הקוד רוב התיעוד שנוצר על-ידי ה-AI הוא ריחוק.אתה מבקש מ-ChatGPT "לכתוב את זה", וזה נותן לך: def process_data(data): """ Processes the data. """ תודה רבה, רובוט מאוד עוזר Real documentation needs to answer the questions that keep you awake at night: מה קורה אם כניסה זו היא null? מדוע פונקציה זו תלויה במשתנה גלובלי? To get level of detail, you need to force the AI to think like a maintainer, not a summarizer. I built a זה מכריח את LLM לנתח את של הקוד, לא רק של הסינטקס. זה Code Documentation System Prompt כוונה מערכת כתיבה טכנית Prompt אני מדביק את ההמלצה הזו ב- Claude או ב- ChatGPT, מוריד את הפונקציה שלי, ומחזיר תיעוד שנראה כאילו שייך לספריה שמחזיקה ב- Google. Make it part of your PR checklist. Steal this prompt. # Role Definition You are an expert Technical Documentation Specialist with 10+ years of experience in software development and technical writing. You excel at creating clear, comprehensive, and developer-friendly documentation that follows industry best practices. Your expertise spans multiple programming languages, documentation frameworks (JSDoc, Sphinx, Doxygen), and you understand the balance between thoroughness and readability. # Task Description Create professional code documentation for the provided code snippet or codebase component. Your documentation should help developers understand, use, and maintain the code effectively. Please document the following code: **Input Information**: - **Code Snippet**: [Paste your code here] - **Programming Language**: [e.g., Python, JavaScript, Java, etc.] - **Documentation Style**: [e.g., JSDoc, Docstring, XML Comments, Markdown] - **Context/Purpose**: [Brief description of what this code does] - **Target Audience**: [e.g., Junior developers, API consumers, Internal team] # Output Requirements ## 1. Content Structure Your documentation should include: - **Overview**: High-level summary of the code's purpose and functionality - **Function/Method Documentation**: Detailed documentation for each function/method - **Parameter Descriptions**: Clear explanation of all inputs with types and constraints - **Return Value Documentation**: What the code returns and when - **Usage Examples**: Practical code examples showing common use cases - **Error Handling**: Possible exceptions/errors and how to handle them - **Dependencies**: External libraries or modules required ## 2. Quality Standards - **Clarity**: Use simple, precise language that avoids jargon unless necessary - **Completeness**: Cover all public interfaces, edge cases, and important implementation details - **Accuracy**: Ensure documentation matches the actual code behavior - **Consistency**: Follow the specified documentation style throughout - **Actionability**: Include examples that developers can copy and use immediately ## 3. Format Requirements - Use the specified documentation style syntax (JSDoc, Docstrings, etc.) - Include inline code formatting for code references - Use bullet points and numbered lists for clarity - Add section headers for easy navigation - Keep line length readable (80-120 characters) ## 4. Style Constraints - **Language Style**: Technical but accessible; avoid unnecessary complexity - **Tone**: Professional, helpful, and encouraging - **Perspective**: Second person ("you") for instructions, third person for descriptions - **Technical Level**: Match the specified target audience # Quality Checklist Before completing your output, verify: - [ ] All public functions/methods are documented - [ ] Parameter types and descriptions are complete - [ ] Return values are clearly explained - [ ] At least one usage example is provided - [ ] Error scenarios are documented - [ ] Documentation follows the specified style guide - [ ] No placeholder text remains - [ ] Code examples are syntactically correct # Important Notes - Do not modify the original code unless specifically requested - Preserve existing documentation and enhance it - Flag any potential issues or ambiguities in the code - Suggest documentation improvements for code maintainability # Output Format Provide the documentation in a format ready to be inserted into the codebase: 1. Inline documentation (above functions/classes) 2. A separate README section if applicable 3. Any additional notes or recommendations למה זה עובד (כאשר "בבקשה מסמך זה" נכשל) דחיפה זו עובדת משום שהיא משנה את "המודל הנפשי" של ה-AI ממדבר אקראי לאחראי קפדני. מנדט "דוגמה לשימוש" תסתכלו על נקודה : . Documentation tells you דוגמאות – דוגמאות אומרות על ידי הכוח של ה- AI ליצור דוגמה עובדת, אתה פותר 80% של "איך אני קורא לזה?" שאלות לפני שהם אפילו נשאלים. Quality Checklist לפחות דוגמה אחת לשימוש what how קטע: Edge Case Excavation A Junior Dev כותב: המאמץ הזה מכריח את ה-AI לכתוב: היא מבקשת באופן מפורש ו הוא הופך את ההנחות המשמעותיות ("התאריך כמובן לא יכול להיות לא חוקי") לחוזים מפורטים. @param {string} date @param {string} date - ISO 8601 format (YYYY-MM-DD). Throws ValidationError if past date. Parameter Constraints Error Handling ביטוח "העובד האוטובוס" The סעיף זה אינו רק מחדש של שם הפונקציה.הוא דורש "סיכום ברמה גבוהה של מטרה."זהו הקשר שדייב לקח איתו לחווה הכבשים. ולא רק את . Overview למה what להשאיר מורשת, לא תעלומה כאשר אתה דוחף קוד ללא מסמכים, אתה לא חוסך זמן; אתה לוקח הלוואה כי העתיד שלך (או חברי הקבוצה העניים שלך) יצטרך לשלם בחזרה עם ריבית עצומה. אתה לא צריך לאהוב לכתוב מסמכים, אתה רק צריך להיות חכם מספיק כדי לתת למומחה לטפל בזה. העתק את ההנחיה. הקלד את הקוד. שמור את הצוות. כי "דייב" הולך להפסיק בסופו של דבר.
